DISTSPHERICAL

The DISTSPHERICAL field specifier allows you to find documents that define a location (latitude and longitude) that is within a specified distance from a specified point.

You can specify the document location using either a pair of fields (corresponding to latitude and longitude values), or a unified GeospatialType field that contains a supported geometric shape in Well-Known Text format.

TIP: If your document location field contains any shape other than a point, IDOL calculates distances from the geometric center of the shape.

Format

FieldText=DISTSPHERICAL{lat,long,dist}:LOCATION
lat The specified latitude. Specify latitude positions south of the equator as negative.
long The specified longitude. Specify longitude positions west of the Greenwich Meridian as negative.
dist The distance in kilometers from the specified latitude and longitude.
LOCATION

The document field or fields that contain the location value. You can use one of the following options to specify location fields:

  • a single field. This field must contain a supported well-known text geometric object. See Supported Well-Known Text Geometric Objects.
  • two fields, in the format LATFIELD:LONGFIELD, where LATFIELD is the field that contains the latitude value, and LONGFIELD is the field that contains the longitude value. You must specify the fields in the order latitude:longitude.

You can specify multiple options for the location fields, in the form LOCATION1:LOCATION2:LOCATION3, and so on. This form can include a mix of types (unified location fields and split latitude and longitude fields).

NOTE: If you use multiple position fields or field pairs, IDOL Content Component cannot match documents where a pair of split geospatial fields occurs interleaved with other geospatial fields. For example, if you use LAT1:LONG1:LOCATION in your query, and these fields occur in a document in the order LAT1, LOCATION, LONG1, IDOL Content Component does not match that document.

In such cases, you can rewrite the query, in the form DISTSPHERICAL{...}:LAT1:LONG1 OR DISTSPHERICAL{...}:LOCATION

NOTE: You can optimize this field specifier by configuring your coordinate fields with the GeospatialType or NumericType property types. If you want to use a single field with well-known text definitions, you can optimize the field specifier only by using the unified GeospatialType property.

Examples

FieldText=DISTSPHERICAL{37.75,-122.4,20}:LAT:LONG

This example matches all documents whose position is within a 20 kilometer radius of San Francisco (37.75N,122.4W). The latitude and longitude position of a document in this example is contained in the fields LAT and LONG, respectively.

FieldText=DISTSPHERICAL{52.2,0.1,20}:LOCATION:LAT:LONG

This example matches all documents whose position is within a 20 kilometer radius of Cambridge (52.2N,0.1W). The latitude and longitude position of a document in this example is contained in either the (unified) LOCATION field, or the LAT and LONG fields.